// 指定包名，管理 OSS 客户端配置类的归属
package com.example.ossmultipart.config; // OSS 客户端配置类所在包

// 导入阿里云 OSS 的客户端构建器与接口
import com.aliyun.oss.OSS; // OSS 客户端接口
import com.aliyun.oss.OSSClientBuilder; // OSS 客户端构建器
// 导入 Spring 注解，用于声明配置类与 Bean
import org.springframework.context.annotation.Bean; // 声明 Bean 注解
import org.springframework.context.annotation.Configuration; // 配置类注解
// 导入 Jakarta 注解，用于在容器销毁前执行清理
import jakarta.annotation.PreDestroy; // Bean 销毁前回调注解
// 导入依赖注入注解与日志工具
import org.springframework.beans.factory.annotation.Autowired; // 依赖注入注解
import org.slf4j.Logger; // 日志接口
import org.slf4j.LoggerFactory; // 日志工厂

// 声明为配置类，提供 OSS 客户端相关 Bean
@Configuration // 声明该类为配置类
public class AliYunOssConfig { // 定义 OSS 客户端配置类

    // 日志记录器，用于输出客户端生命周期日志
    private static final Logger log = LoggerFactory.getLogger(AliYunOssConfig.class); // 初始化日志记录器

    // 注入属性配置类，提供 endpoint 与密钥等信息
    @Autowired // 从容器中注入属性配置
    private AliYunOssProperties properties; // OSS 配置属性引用

    // 保存全局唯一的 OSS 客户端实例，供全局使用
    private OSS ossClient; // OSS 客户端实例缓存

    // 创建并注册 OSS 客户端 Bean，供其他组件使用
    @Bean // 声明一个 Bean 给 Spring 容器
    public OSS ossClient() { // 提供 OSS 客户端实例的方法
        // 使用 OSSClientBuilder 根据 endpoint、accessKeyId、accessKeySecret 创建客户端
        this.ossClient = new OSSClientBuilder().build(
                properties.getEndpoint(), // 设置访问域名
                properties.getAccessKeyId(), // 设置 AccessKeyId
                properties.getAccessKeySecret() // 设置 AccessKeySecret
        ); // 构建 OSS 客户端
        log.info("OSS 客户端已初始化，endpoint={}", properties.getEndpoint()); // 打印初始化日志
        return this.ossClient; // 返回客户端实例供容器管理
    } // ossClient 方法结束

    // 在容器销毁前关闭 OSS 客户端，释放资源
    @PreDestroy // 容器销毁前回调
    public void shutdown() { // 关闭客户端方法
        if (this.ossClient != null) { // 判断客户端是否已创建
            try { // 捕获可能的异常
                this.ossClient.shutdown(); // 关闭 OSS 客户端连接
                log.info("OSS 客户端已关闭"); // 打印关闭日志
            } catch (Exception e) { // 关闭过程中出现异常
                log.warn("关闭 OSS 客户端时发生异常: {}", e.getMessage()); // 打印警告日志
            } // 异常处理结束
        } // 客户端非空判断结束
    } // shutdown 方法结束
} // 配置类结束